### Symbol visibility
Any symbol that is not explicitly annotated using a `GDK_AVAILABLE_IN_*`
-macro is considered internal, and not exported in the shared library.
+or `GDK_DEPRECATED_IN_*` macro is considered internal, and not exported
+in the shared library.
Never export variables as public API, since this is cumbersome on some
platforms. It is always preferable to add getters and setters instead.
Non-exported functions that are needed in more than one source file
-should be declared in a private header file.
+should be declared in a private header file with a name that ends in
+`private.h`.
Non-exported functions that are only needed in one source file
should be declared static.
### Documentation
-All public APIs must have gtk-doc comments. For functions, these should
+All public APIs must have doc comments. For functions, these should
be placed in the source file, directly above the function.
```c
/* valid */
/**
* gtk_get_flow:
- * @widget: a #GtkWidget
+ * @widget: a `GtkWidget`
*
* Gets the flow of a widget.
*
Doc comments for macros, function types, class structs, etc should be
placed next to the definitions, typically in headers.
-Section introductions should be placed in the source file they describe,
-after the license header:
+The main content of the doc comments uses markdown, which can include
+inline formatting, sections, tables, images, links. For links to
+symbols/classes/etc, we use a markdown extension syntax like this:
+
+[class@Gtk.Widget], [method@Gtk.ListView.get_factory],...
+
+Every doc comment should start with a single-sentence paragraph that
+can serve as a summary of sorts (it will often be placed next to a
+link pointing to the full documentation for the symbol/class/etc).
+The summary should not include links.
+
+Long-form documentation for classes should be included in the doc
+comment for the struct, typically at the top of the source file,
+after the license header and includes:
```c
- /* valid */
/**
- * SECTION:gtksizerequest
- * @Short_Description: Height-for-width geometry management
- * @Title: GtkSizeRequest
+ * GtkSizeRequest:
+ *
+ * The GtkSizeRequest interface is GTK's height-for-width geometry
+ * geometry management system.
+ *
+ * # Geometry management
*
- * The GtkSizeRequest interface is GTK's height-for-width (and
- * width-for-height) geometry management system.
* ...
*/
```
-To properly document a new function, macro, function type or struct,
-it needs to be listed in the `sections.txt` file.
-
-To properly document a new class, it needs to be given its own section
-in the sections.txt, needs to be included in the `docs.xml` file, and the
-`get_type` function needs to listed in the `.types` file.
-
For more information on the documentation style and contribution guidelines,
please [follow the corresponding contribution guide](./reference/README.md).
source code
- static pages that provide an overview of specific sections of the API
-In both cases, the contents are parsed, converted into DocBook format, and
-cross-linked in order to match types, functions, signals, and properties.
-From the DocBook output, we generate HTML, which can be used to read the
-documentation both offline and online.
+In both cases, the contents are parsed as markdown and cross-linked in order
+to match types, functions, signals, and properties. Ultimatively, we generate
+HTML, which can be used to read the documentation both offline and online.
-In both cases, contributing to the GTK documentation requires modifying
-files tracked in the source control repository, and follows the same steps
-as any other code contribution as outlined in the GTK [contribution
-guide][contributing]. Please, refer to that document for any further
-question on the mechanics of contributing to GTK.
+Contributing to the GTK documentation requires modifying files tracked in the
+source control repository, and follows the same steps as any other code
+contribution as outlined in the GTK [contribution guide][contributing].
+Please, refer to that document for any further question on the mechanics
+of contributing to GTK.
-GTK uses [gtk-doc][gtkdoc] to generate its documentation. Please, visit the
-gtk-doc website to read the project's documentation.
+GTK uses [gi-docgen][gidocgen] to generate its documentation. Please, visit
+the gi-docgen website to read the project's documentation.
[contributing]: ../../CONTRIBUTING.md
-[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc
+[gi-docgen]: https://gitlab.gnome.org/ebassi/gi-docgen
## Contributing to the API reference
*/
gboolean
gtk_foo_set_bar (GtkFoo *self,
- GtkBar *bar)
+ GtkBar *bar)
{
...
```
For more information on the available link formats, see the gi-docgen
documentation.
+Every doc comment should start with a single-sentence paragraph that
+can serve as a summary of sorts (it will often be placed next to a
+link pointing to the full documentation for the symbol/class/etc).
+The summary should not include links.
+
### Introspection annotations
The purpose of the annotations for function arguments, properties, signals,
custom GtkBuildable implementation
- the CSS element name to be used by selectors
- the CSS selector hierarchy for children, in case of a composite widget
+ - the accessible role of the class
Each section in a type description can have a heading; it's preferred to use
second and third level headings only.
projects / gtk4.git / commitdiff